react-visibility-sensor

React Visibility Sensor

Sensor component for React that notifies you when it goes in or out of the window viewport.

Sponsored by X-Team

Install

npm install react-visibility-sensor

Including the script directly

Useful if you want to use with bower, or in a plain old <script> tag.

In this case, make sure that React and ReactDOM are already loaded and globally accessible.

• Plain: https://unpkg.com/react-visibility-sensor@3.4.0/dist/visibility-sensor.js
• Minified https://unpkg.com/react-visibility-sensor@3.4.0/dist/visibility-sensor.min.js

Take a look at the umd example to see this in action

Example

View the example

To run the example locally:

• npm run build-example
• open example/index.html in a browser

General usage goes something like:

function render () {
  var VisibilitySensor = require('react-visibility-sensor');

  var onChange = function (isVisible) {
    console.log('Element is now %s', isVisible ? 'visible' : 'hidden');
  };

  return (
    <VisibilitySensor onChange={onChange} />
  );
}

You can also pass a child function, which can be convenient if you don't need to store the visibility anywhere:

return (
  <VisibilitySensor>
    {({isVisible}) =>
      <div>I am {isVisible ? 'visible' : 'invisible'}</div>
    }
  </VisibilitySensor>
);

Props

• onChange: callback for whenever the element changes from being within the window viewport or not. Function is called with 1 argument (isVisible: boolean)
• active: (default true) boolean flag for enabling / disabling the sensor. When active !== true the sensor will not fire the onChange callback.
• partialVisibility: (default false) consider element visible if only part of it is visible. Also possible values are - 'top', 'right', 'bottom', 'left' - in case it's needed to detect when one of these become visible explicitly.
• offset: (default {}) with offset you can define amount of px from one side when the visibility should already change. So in example setting offset={{top:10}} means that the visibility changes hidden when there is less than 10px to top of the viewport. Offset works along with partialVisibility
• minTopValue: (default 0) consider element visible if only part of it is visible and a minimum amount of pixels could be set, so if at least 100px are in viewport, we mark element as visible.
• intervalCheck: (default true) when this is true, it gives you the possibility to check if the element is in view even if it wasn't because of a user scroll
• intervalDelay: (default 100) integer, number of milliseconds between checking the element's position in relation the the window viewport. Making this number too low will have a negative impact on performance.
• scrollCheck: (default: false) by making this true, the scroll listener is enabled.
• scrollDelay: (default: 250) is the debounce rate at which the check is triggered. Ex: 250ms after the user stopped scrolling.
• scrollThrottle: (default: -1) by specifying a value > -1, you are enabling throttle instead of the delay to trigger checks on scroll event. Throttle supercedes delay.
• resizeCheck: (default: false) by making this true, the resize listener is enabled. Resize listener only listens to the window.
• resizeDelay: (default: 250) is the debounce rate at which the check is triggered. Ex: 250ms after the user stopped resizing.
• resizeThrottle: (default: -1) by specifying a value > -1, you are enabling throttle instead of the delay to trigger checks on resize event. Throttle supercedes delay.
• containment: (optional) element to use as a viewport when checking visibility. Default behaviour is to use the browser window as viewport.
• delayedCall: (default false) if is set to true, wont execute on page load ( prevents react apps triggering elements as visible before styles are loaded )
• children: can be a React element or a function. If you provide a function, it will be called with 1 argument {isVisible: ?boolean, visibilityRect: Object}

It's possible to use both intervalCheck and scrollCheck together. This means you can detect most visibility changes quickly with scrollCheck, and an intervalCheck with a higher intervalDelay will act as a fallback for other visibility events, such as resize of a container.

Thanks

Special thanks to contributors:

• Andrew Hong
• Oleg Slobodskoi
• EugeneHlushko
• Stefan B
• Radu-Sebastian Amarie
• Roope Merikukka
• Christian Davis
• Anton Fedchenko
• Mateusz Burzyński
• Zak Linder
• Andarist
• Andy Edwards
• Bram Schulting
• Dan Abramov
• Daniel Stefanovic
• Eric Bower
• Julien Bachmann
• Neehar Venugopal
• Rubens Mariuzzo
• Tim Tyrrell

License

MIT

Similar packages

Other packages similar to react-visibility-sensor

react-intersection-observer

The react-intersection-observer package provides a React implementation of the Intersection Observer API, which allows you to observe changes in the intersection of a target element with an ancestor element or with a top-level document's viewport. It is more flexible and performant compared to react-visibility-sensor, especially for complex visibility detection scenarios.

react-waypoint

The react-waypoint package allows you to execute a function whenever you scroll to an element. It is useful for triggering animations or loading content as the user scrolls. Compared to react-visibility-sensor, react-waypoint is more focused on scroll-based triggers and offers more control over when the callbacks are fired.